This is a small guide for Hextracker(version 0.836).
====================================================

Please remember that this program will remain BETA for ever !
The author refuses any blaming for any errors detected !
This program MUST not be sold as it was given by the author to the Atari comunity.
This program should work both in colour and mono mode with a 512Kb STF/E but 1MB or more is better.
It can handle from 1 up to 16 voices but up to 8 will be better.
The user has full volume and pitch control(3 octaves) for each voice.


Now to the buttons :) !

EXIT: left click on top left corner (DON'T FORGET TO SAVE !!!!!!!).

POSITION: selects the song position from 0 to END POSITION
- arrow up: goes to position +1 or +$10 up to END POSITION
- arrow down: goes to position -1 or -$10 down to 0
- digits: selects the increments/decrements 1 or $10

PATTERN: selects the pattern for the song position from 0 to $FF
- arrow up: increase the pattern number by 1 or $10
- arrow down: decrease the pattern number by 1 or $10
- digits: selects the increments/decrements 1 or $10

END POSiTION: sets the song length from 0(1 position) to $FF(256 positions)
- arrow up: increase the end position number by 1 or $10
- arrow down: decrease the end position number by 1 or $10
- digits: selects the increments/decrements 1 or $10

RESTART POS: selects the song restart position from 0 to END POSITION
- arrow up: goes to position +1 or +$10 up to END POSITION
- arrow down: goes to position -1 or -$10 down to 0
- digits: selects the increments/decrements 1 or $10

SAMPLE: selects the current SAMPLE from 1 to $FF
- arrow up: increase the sample number by 1 or $10
- arrow down: decrease the sample number by 1 or $10
- digits: selects the increments/decrements 1 or $10

LENGTH: adjusts the sample length decreasing it at the start or at the end
- left arrow down: decrease the sample length at the start by 1, $10 ... $100000 dwon to 0
- right arrow down: decrease the sample length at the end by 1, $10 ... $100000 dwon to 0
- digits: selects the decrements 1, $10, $100, $1000, $10000 or $100000

REPSTRT: sets the loop start position from 0 to sample length
- arrow up: increase the loop start position by 1 or $10 ... $100000 up to sample length
- arrow down: decrease the loop start position by 1 or $10 ... $100000 down to 0
- digits: selects the increments/decrements 1, $10, $100, $1000, $10000 or $100000

LOOPLEN: sets the loop length from 0 to sample length
- arrow up: increase the loop length by 1 or $10 ... $100000 up to sample length - loop start
- arrow down: decrease the loop length by 1 or $10 ... $100000 down to 0
- digits: selects the increments/decrements 1, $10, $100, $1000, $10000 or $100000

VOLUME: sets the default volume for the sample from 0 to $40
- arrow up: increase the sample default volume by 1 or $10 up to $40
- arrow down: decrease the sample number by 1 or $10 down to 0
- digits: selects the increments/decrements 1 or $10

SONGNAME: click on the name/spaces to edit
SAMPLENAME: click on the name/spaces to edit
TEXT EDITOR:
- mouse selects edit position
- insert toggles insert/replace mode
- arrows, backspace and delete allowed
- return/enter ends editor

SONG: info size in bytes of the MOD
MEMORY: info size in bytes of the memory left
DISK: click on it to get the size available on the working disk

MESSAGE: information that may sometimes wait for space or editor key when the mouse pointer is hidden

NCHAN: set the number of voices from 1 to 16 (value in decimal)
- arrow up: increase the number os voices by 1 up to 16
- arrow down: decrease the number of voices by 1 down to 0

HEXTRACKER: shows some info about the utility

PLAY: plays the song in TRACK mode ! (numeric pad toggles voices / enter sets all)
Space stops.
Play can also automaticaly stop if:
- there is not enough memory
- there is no CPU time left
- a song error is found like non existing pattern or sample
- ...

PATTERN: sets Pattern mode that will keep playing the same pattern

RECORD: will allow pressed keys to be stored in the current voice in the MOD data as if a sample was played while the MOD is played

EDIT: allows pattern data to be edited manually

The tone keys support 3 octaves with HELP/UNDO to select low octave (0/1).
The keyboard keys are the standard ones like in PT 2.1 .

PRINT: will print the MOD

FSAMPL: sets the base frequency for all samples.
Default value for MOD is 9855 Hz in decimal that should be the sampling rate for a D#2
or it can be 8287 Hz for a C-2.
If you sample a A-2 then you should sample it at 9855*2^(6/12) = 13937 Hz.
The A is 6 steps after the D#2 and 1 octave has 12 steps.
If you start from C then we have 9 steps: 8287*2^(9/12) = 13937 Hz.
If we have a B-3 then from D#2, we have 20 steps: 9855*2^(20/12) = 31288 Hz.
Going to octave 1, the rule is the same but with negative steps.
This allows to have higher frequency (and better quality) samples.
- arrow up: increase the samples frequency by 1, 10, 100, 1000, 10000 up to 65535 Hz
- arrow down: decrease the samples frequency by 1, 10, 100, 1000, 10000 down to 100 Hz (be careful !)

OUTPUT: toggles the OUTPUT and DISK panels

OUTPUT panel:
- Arrows select output type (all except YM and STE were not tested with the HW)
  STE tested with Steem 3.2 !
- Arrows select replay frequency (if it is too much the player will stop !)
  STE frequency possibilities are measured from your real HW !
- Arrows set the Volume/Quality factor
- DIST option will calculate the optimum V/Q factor after the complete MOD was played once.
  That value is different for mono and stereo mode.
  That value is inicialized to half of the number of voices (4 voices -> 2.0)
- DATA DIST option when selected displays the pattern data while playing
- VU METER option when selected displays some VU meters up to 8 channels (please notice how looped samples persist ...)
- DIGISCOPE option will display the graphical pic of the data sent to the output device
  (maximum 352 dots => 17.5 KHz (more frequency will lead to same amount of dots))
- SAMPL: selects the sample type to be loaded/saved signed or unsigned

DISK panel:
- LOAD SAMP: loads sample
- SAVE SAMP: saves sample
- LOAD MOD: loads MOD (several formats can be imported (TCB, OKT, Protracker(s), STE Oktalyser, Fast Tracker / Take Tracker))
- SAVE MOD: saves the MOD in Hextracker format
- LOAD SONG: loads the song part and looks for the samples in the same directory
- SAVE SONG: saves the song part
- DEL FILE: delete file

TRACK/SAMPL: toggles TRACK and SAMPL mode that will allow a better sample size adjustment

PATTERN DATA:
- left top corner: select pattern
- Arrows up, down, left, right to move around (presh shift to go faster)
- Numpad to select sample (0 and . to select group of 16 then digit enter selects 1)
  or numbers if not in the tone column
- Shift Numpad to go to voice
- Clr Home to go to first pattern row
- Shift Clr Home to go to the pattern on first song position, first row, first voice
- Backspace goes up (and clears in Edit mode)
- Return goes down but to tone position
- Tab goes to tone position and then jumps to next voice
- Shift Tab goes to tone position and then to previous voice
- # to go to the first voice
- shift # to go to the last voice
- Digits, A, B, C, D, E, F and delete (or shift delete) to edit
- Insert to create pattern
- Shift Insert to create a pattern on the first available space
- Crotchets: turn voice on/off
- Space plays
- Shift spaces switches the current Pattern mode and plays
- F1: marks start of block
- F2: marks end of block
- F3: copy marked block for the cursor voice
- F4: copy marked block from the cursor voice to the marked voice(+F1)
- F5: copy marked block from the cursor voice to all voices
- F6: copy marked block for all voices
- F7: copy marked block from the current pattern to the marked pattern(+F2) for all voices
- F8: copy cursor voice to marked voice for all patterns
- F9: - $10 positions
- F10: + $10 positions
- +F1: marks voice
- +F2: marks pattern
- +F3: switch marked voice with cursor voice for all patterns
- +F4: deletes the contents of cursor voice for all patterns
- +F5: delete row data
- +F6: clears block marked by F1 and F2 including limits but only on the cursor voice
- +F7: clears block marked by F1 and F2 including limits on all voices
- +F8: clears a pattern
- +F9: deletes a pattern
- +F10: deletes a sample

Playing will stop if an error is detected like no sample, no pattern ...

Known issues:
=============
- TCB Tracker and OKTalyser formats may be not fully read due to lack of documentation;
- Extended octaves are not supported and lead to a crash so the support of Take tracker and Fast tracker files is limited;
- BPM, finetune and update funk commands are ignored and not supported;
- Mod loading does not check for all error possibilities in the file;
- Some issues with memory not restored with load/save sample;
- Config.inf file is for a QWERTY keyboard !!! (128 bytes without shift + 128 bytes with)
- Mixing routs have been built for STF so for STE Lance's player is much better for 4 voices MODs (twice faster);

Have fun,
Paulo.



Annex 1:

Minimum replay frequencies possible (in MONO with YM2149 (color mode)):

Tone keys: 30720

/* Nothing */
16 -  9600
14 - 10778
12 - 12288
10 - 14456
 8 - 17066
 6 - 20480
 4 - 27306

/* Worse (Dist + Data - VU + Digiscope) */
16 -  5120
14 -  5742
12 -  6536
10 -  7402
 8 -  8533
 6 - 11170
 4 - 14985

/* Just Dist */
16 -  9035
14 - 10072
12 - 11377
10 - 13072
 8 - 15360
 6 - 18070
 4 - 22755

/* Just Scrolling Data */
16 -  6083
14 -  6981
12 -  7979
10 -  9309
 8 - 11170
 6 - 15360
 4 - 21942

/* Dist + Scrolling Data */
16 -  5715
14 -  6467
12 -  7402
10 -  8533
 8 - 10072
 6 - 13653
 4 - 18618

/* Just VU */
16 -  7979
14 -  9170
12 - 10685
10 - 12538
 8 - 15360
 6 - 19200
 4 - 25600

/* Just Digiscope */
16 -  8533
14 -  9600
12 - 10778
10 - 12288
 8 - 14288
 6 - 16605
 4 - 21186

/* Data + VU */
16 -  6536
14 -  7492
12 -  8777
10 - 10413
 8 - 12934
 6 - 16605
 4 - 23630

/* Data + Disgiscope */
16 -  5437
14 -  6083
12 -  6981
10 -  7979
 8 -  9309
 6 - 12288
 4 - 16605

/* VU + Digiscope */
16 -  7062
14 -  8084
12 -  9309
10 - 10778
 8 - 12800
 6 - 15360
 4 - 19819

/* Data + Digiscope + VU */
16 -  5796
14 -  6642
12 -  7680
10 -  8904
 8 - 10778
 6 - 13653
 4 - 18070


STE (with nothing):
- 4 voices at 50KHz
- 6 voices at 25 KHz
- 8 voices 25KHz in mono and for most in stereo
- 12 voices at 12.5 KHz in mono (some at 16.7) and stereo
- 16 voices 10 KHz in mono (some at 12.5) and stereo

STE Stereo (worst case):
- 4 voices at 16.7 KHz
- 6 voices at 10 KHz
- 8 voices at 7.15 KHz
- 12 voices at 6.25 KHz
- 16 voices at 4.18 KHz

STE Mono (worst case):
- 4 voices at 16.7 KHz
- 6 voices at 12.5 KHz
- 8 voices at 10 KHz
- 12 voices at 7.15 KHz
- 16 voices at 5 KHz

STE Stereo (Data + Disgiscope):
- 4 voices at 25 KHz
- 6 voices at 12.5 KHz
- 8 voices at 8.34 KHz
- 12 voices at 6.25 KHz
- 16 voices at 5 KHz

STE Mono (Data + Disgiscope):
- 4 voices at 25 KHz
- 6 voices at 12.5 KHz
- 8 voices at 10 KHz
- 12 voices at 7.15 KHz
- 16 voices at 6.25 KHz

STE Stereo (Data only):
- 4 voices at 25 KHz
- 6 voices at 16.7 KHz
- 8 voices at 12.5 KHz
- 12 voices at 8.34 KHz
- 16 voices at 6.25 KHz

STE Mono (Data only):
- 4 voices at 50 KHz
- 6 voices at 25 KHz
- 8 voices at 12.5 KHz
- 12 voices at 8.34 KHz
- 16 voices at 6.25 KHz


Emulators note:
Steem 3.2 at 32MHz allows 16 voices mono/stereo on STE mode at 50 KHz with all.
This is especially nice to find the correct VQs ...
Steem 3.2 at 40MHz allows 61.44 KHz on YM2149 will all.


Annex2: Hectracker file format

***************************************************************************
*	HEXTRACKER FORMAT
*
* $00		'HEXTRACK'			8 bytes
* $08		MOD NAME			20 bytes
* $1C@7...4	RESERVED FOR FUTURE USE		4 bits
* $1C@3...0	NUMBER OF VOICES - 1		4 bits
* $1D		VQ FACTOR			1 byte
* $1E		PATTERN LIST LENGTH(PLL) - 1	1 byte
* $1F		RESTART PATTERN LIST INDEX	1 byte
* $20		PATTERN LIST			PLL (or +1) to even number
* $20+PLL	PATTERNS CONTROL BITMAP		256 bits
* $40+PLL	EXISTING PATTERNS PACKED	variable
* variable	SAMPLES BASE FREQUENCY		2 bytes
* variable	SAMPLES CONTROL BITMAP		256 bits
* variable	SAMPLES DESCRIPTORS		32 bytes each
* variable	SAMPLES				variable
***************************************************************************
VQ $10 => no amplification , $18 amplify 1.5 times, $20 amplifly  2 times ...
Bitmaps 0 pattern/sample not included   1 pattern/sample included
SAMPLES BASE FREQUENCY: 9855 for default Amiga/Protracker for other value the samples have to be played x/9855 times faster
SAMPLES DESCRIPTORS:
		$00		sample name		22 bytes
		$16		size			3 bytes
		$19		repeat start		3 bytes
		$1C		loop size		3 bytes
		$1F		volume(0-64($40))	1 byte

Packed pattern data:
====================
First byte bits 7 and 6:

	00	=> Read 4 bytes like UNPACKED data
		Byte 1: Tone    0 -> 36 ( 0: no tone 1: B-3 ... 36: C-1 )
		Byte 2: Sample number
		Byte 3: Effect number (0 -> F)
		Byte 4: Effect data (0 -> FF)

		Bytes 3 and 4: $0xxx where xxx is equal to Protracker data
		Examples:
		- effect 4(vibrato) and data $A1 => $04A1
		- effect $E6(loop) and data 0 (set loop) => $0E60

	01	=> Read 2 bytes and clear bit 6:
		Byte 1: Tone    0 -> 36 ( 0: no tone 1: B-3 ... 36: C-1 )
		Byte 2: Sample number
		Effect number = 0
		Effect data = 00

	10	=> Read 2 bytes and clear bit 7:
		Byte 1: Effect number (0 -> F)
		Byte 2: Effect data (0 -> FF)
		Tone = 0;
		Sample number = 0

	11	=> Read 1 byte and clear bits 6 and 7:
		Byte 1: Tone    0 -> 36 ( 0: no tone 1: B-3 ... 36: C-1 )
		Sample number = 0
		Effect number = 0
		Effect data = 00



****	Get and unpack data

	moveq	#0,d0
	moveq	#0,d1
*	moveq	#0,d2							UPK
*	move.b	(a1)+,d0						UPK
*	move.b	(a1)+,d1						UPK
*	move.b	(a1)+,batribute(a3)					UPK
*	move.b	(a1)+,d2						UPK
	moveq	#6,d2							PCK
	move.b	(a1)+,d0			1st byte		PCK
	bpl.s	toca06				positive ?  yes	%0X	PCK
	and.b	#$7F,d0				7 bits only	%1X	PCK
	bclr	d2,d0				test and clear bit 6	PCK
	bne.s	toca07				set ? yes	%11	PCK
	move.b	d0,batribute(a3)				%10	PCK
	move.b	(a1)+,d2						PCK
	moveq	#0,d0							PCK
	bra.s	toca09							PCK
toca06:
	move.b	(a1)+,d1					%0X	PCK
	bclr	d2,d0				test and clear bit 6	PCK
	beq.s	toca08				set ? no	%01	PCK
toca07:
	moveq	#0,d2							PCK
	clr.b	batribute(a3)						PCK
	bra.s	toca09							PCK
toca08:
	move.b	(a1)+,batribute(a3)				%00	PCK
	move.b	(a1)+,d2						PCK
toca09:


